home *** CD-ROM | disk | FTP | other *** search
/ Dr. Windows 3 / dr win3.zip / dr win3 / PROGRAMR / IL2HDK30.ZIP / IL2HDK.DOC < prev    next >
Text File  |  1993-11-10  |  20KB  |  459 lines
  1. *******************************************************************************
  2. *                                   il2hdk                                    *
  3. * Interrupt List to help development kit conversion program.                  *
  4. * Version 3.0, Last Update Nov. 07, 1993.                                     *
  5. *******************************************************************************
  6.  
  7.  
  8. What's New
  9. ----------
  10.  
  11. 1. Added Browse Sequences generation for interrupts and Ralf Brown topics.
  12.  
  13. 2. Incorporate the files MEMORY.LST, PORTS.LST, CMOS.LST AND 86BUGS.LST that
  14.    are shiped with the interrupt list to the hypertext database.
  15.  
  16. 3. This version needs HLPDK Sound & Vision Edition (V10.0) to compile.
  17.  
  18.  
  19. Overview
  20. --------
  21.  
  22. il2hdk is a conversion program from Ralf Brown's interrupt list to the help
  23. development kit (hlpdk) .HDF source format. 
  24.  
  25. This program will convert the original interrupt list to a hypertext database
  26. that can be converted using the helpC compiler included with the help 
  27. development kit to any one of the target formats supported by this compiler.
  28.  
  29. This generated database is not intended to replace the interrupt list, it is 
  30. just a compilation of the hypertext version. The nice thing about this 
  31. hypertext database is that it includes nice hot-links, and easy to use database
  32. structure with categories, indexes and directories, there are glossary
  33. "hints" in the text, and easy to use keyword search is supported.
  34.  
  35. With the introduction of this tool, and the HPC2HDK conversion program by 
  36. Yaniv Golan, 2 of the most interesting reference tools available to PC 
  37. programmers are introduced in a hypertext format, in a format you might find
  38. useful.
  39.  
  40. You might find NG2HDK that converts from the Norton Guides to HLPDK format 
  41. another alternative to keep your accumalated wizdom up to date, and POPHDK 
  42. that converts from POPHELP to HLPDK as well. (Yaniv Golan's work - again).
  43.  
  44. Requirments
  45. -----------
  46.  
  47. In order to use this program you will need the following things :
  48.  
  49. 1. Ralf Brown's interrupt list - available on your favourite sites on the
  50.    internet as INTERxxn, where xx stands for the latest version of the
  51.    interrupt list (36 is the version number of the list that is available
  52.    on the net when this document is written), and n stands for a part number
  53.    (A, B or C as of today..).
  54.  
  55. 2. This package (obviously).
  56.  
  57. 3. A PC that can run DPMI applications for the conversion program, with as much
  58.    memory as possible. (I have tested this program in an OS/2 VDM restricted
  59.    to 2MB of DPMI memory, so it can be assumed that any PC with more than 3MB
  60.    of memory will be able to run this program. Please notice, however, that 
  61.    future versions of the interrupt list might be much bigger than the current 
  62.    version, so more memory might be needed).
  63.  
  64. 4. The help development kit, a shareware product written by myself, that can
  65.    produce help databases or help databases sources to different environments
  66.    from the same source. The help development kit is available on the internet
  67.    in the simtel hypertext and garbo programming directories, on the WINSDK
  68.    forum, WINHELP section of COMPUSERVE and the JCS Marketing shareware CD-ROM.
  69.    You can probably find it on other CD-ROMS that include the internet archives,
  70.    as well as other sources. The current version is HLPDK 10.0, available as 
  71.    HDK100A.ZIP and HDK100B.ZIP in an archive site/bbs/forum library near you.
  72.  
  73. 5. [OPTIONAL] - A help compiler for your specific environment - if you do not
  74.    generate the code to one of the native help engines included with the 
  75.    help development kit, the code will have to be compiled with the specific
  76.    help compiler.
  77.  
  78. 6. Time, and Disk Space. The interrupt list is BIG, the il2hdk program tries to
  79.    convert this list to a smart database with hot-links, and easy navigational
  80.    structures. This process takes time, and - Disk Space. (As can be seen in
  81.    the 3rd entry of this section above - memory is needed as well).
  82.  
  83. Operation
  84. ---------
  85.  
  86.  
  87. 0. Well - you know - just do it, oh well, I will be more specific.
  88.  
  89. 1. Move the contents of this package to the directory of the interrupt list
  90.    files. (Not mandatory - only recommended).
  91.  
  92. 2. Check the INTLST.LST file provided with this package to see if all the files
  93.    of the interrupt list are specified in it, (or if you use the combine.bat
  94.    file that came with the interrupt list), and modify it if neccesary.
  95.  
  96. 3. execute the convertor by typing IL2HDK on the command line. (I do not 
  97.    promise, but you can say that you heard of a GUI icon ridden version,
  98.    working as a distributed object with 216 bit technology sometime in the
  99.    future).
  100.  
  101. 4. Use to helpC compiler from the help development kit package to compile for
  102.    you target. (e.g. To compile for Windows 3.1 - HELPC /W31 /R- INTRPTS).
  103.  
  104. 5. [Optional] - Use your help compiler for the final pass (e.g. - To compile
  105.    to Windows 3.1 use the Microsoft HCP program - HCP INTRPTS).
  106.  
  107. > Please issue IL2HDK /? for a list of the switches available to the
  108.   conversion program.
  109.  
  110. > You may want to add glossary items to the glossary file, or additional
  111.   glossary files, please consult the Tech-Talk section below.
  112.  
  113. File List
  114. ---------
  115.  
  116. This package contains the following files :
  117.  
  118. IL2HDK  .EXE    - The convertor program exexcutable.
  119. DPMI16BI.OVL    - Borland's DPMI Server.
  120. RTM     .EXE    - Borland's Dos Extender Run Time Module.
  121. IL2HDK  .DOC    - This File.
  122. CTGCNV  .LST    - Category Conversion List Hints file.
  123. INTLST  .LST    - Default interrupt list file list.
  124. GLSLST  .LST    - Glossary files list.
  125.  
  126. Advertisment
  127. ------------
  128.  
  129. Buy 2,  Get 3 FREE!. (ACT Now!, A limited time offer).
  130.  
  131. Known Bugs
  132. ----------
  133.  
  134. 0. WHAT???, BUGS???, HERE???, IN MY PROGRAM???. Every thing works as 
  135.    advertised. (See above).
  136.  
  137. 1. The database is so BIG that some targets supported by the helpC compiler
  138.    failed to operate.
  139.  
  140.  A. HC31 will not compile the intrpts.hpj and intrpts.rtf sources created by
  141.     helpC. You must use HCP - the protected mode windows help compiler.
  142.  B. Borland's Help Linker 6.10 causes exception 12 when it tries to compile 
  143.     the helpC output using HL -e100 -x -p -i INTRPTS.HL . Maybe Version 6.0
  144.     will work. If anyone knows of a way around this, please tell me. (I was
  145.     told by Borland Rep. that the problem was sent to QA hopefully for a fix ..).
  146.  C. The Native Memory format can not support this database, there are too many
  147.     links. The Naive Paradox based format works. (But it is slow in the current
  148.     implementation).
  149.  D. OS/2 IPF fails, because a topic can have a maximum of 16000 words, and 
  150.     because some of the directories (such as the interrupt 2f directory) can be
  151.     very large, IPFC will fail. IBM's ANN FORD told me on CIS that a future
  152.     version of IPF will be a clean 32 bit version, and will support more words
  153.     per topic.
  154.  E. HCP - Apparantly, if HCP does not have enough memory, it will fail to 
  155.     create the correct contents screen. The database will be created, but,
  156.     the first topic that will be presented is the first topic in the RTF
  157.     file. Compiling with HCP in a 8MB DOS VDM under OS/2 works for me, in 
  158.     a 2MB window, HCP did not create the correct contents topic.
  159.  E. I have not tried any other formats, so if you do, please tell me.
  160.  
  161. 2. The helpC compiler failed with a run-time error 203.
  162.  
  163.  A. Some targets can not be compiled in the shareware version of the help 
  164.     development kit. DV/X, OS/2, POPHELP, Text and Native/Mem targets need
  165.     a symbol table that is built by helpC in memory, the shareware version
  166.     works in real mode and is restricted to 640K (or a bit more ..), which
  167.     is not enough to create the symbol table for such a huge database. Please
  168.     use the registered version helpCX protected mode compiler for these 
  169.     targets.
  170.  
  171. 3. The helpC compiler can not create the Cross Regerence Report.
  172.  
  173.  A. Please use the helpCX protected mode compiler (included with the registered
  174.     version of the help development kit). The cross reference report